Belgian Amiga Club - ADF Collection/BS1 part 19.zip/BS1 part 19/Doc Disk 5 BS1.adf/PowerWindows2.5

Text File | 1988-12-10 | 52KB | 1,015 lines

PowerWindows 2.5 is the interactive, interface programming aid for the Amiga
 computer. It provides you, the programmer, the ability to quickly create and
 edit screens, windows, menus, and gadgets for your programs, with none of
 the fuss or tedium of coding the necessary structures yourself. All you have
 to do is move a mouse and push a button to:

     create new screens and windows;
     edit old screens and windows;
     "grab" (import) windows running elsewhere in the system;
     add, move, delete, or edit window text;
     modify window characteristics;
     include or exclude IDCMP or other window flags;
     add, move, edit or delete a menu;
     add, move, edit or delete items and subitems in a menu;
     add gadgets, move gadgets, clone gadgets, re-size gadgets,
          set gadget characteristics, enter gadget text, and
          delete gadgets;
     add and manipulate Knob, PopUpMenu, and DragGadget
          constructs as used with InovaTools1;
     include IFF brush imagery in your gadgets or menus;
     generate source code for all of the above;
     and save your creations on disk for future editing.

PowerWindows provides you with instant feedback, allowing you to see exactly
 how your creation will look without the trial-and-error of the
 edit/compile/examine loop. You can effectively see your windows outside your
 program, complete with menus, menuitems, subitems, text and gadgets -- almost
 as if you were already running your program. When you are satisfied, select
 your language and PowerWindows creates the structures for you. Save your
 design in the intermediate file format so that it will be available should
 you ever need to modify or add to it, or generate the same data for a
 different language.

NOTE: You will need to provide the necessary entry points or procedure names
 to properly interface the generated code with your program.

REQUIREMENTS: Amiga with 512K RAM and at least one disk drive, with
 KickStart/Intuition version 1.2. Also required are the necessary include
 files for the language of your choice which define the Intuition structures
 that PowerWindows generates.

GETTING STARTED:

PowerWindows requires no installation. We recommend that you make a copy of
 PowerWindows and put the original in a safe place, away from hazards like
 fire, strong magnetic fields, and pirates. Use the copy as a "master", and
 use the original only for making new legal copies.

Unlike the program, you might require some installation yourself. This
 software expects you to be familiar  with the Amiga and with the programming
 language of your choice. This means that we won't be defining terms like
 drag bar (no jokes, please) or gadget. PowerWindows is a serious tool for
 serious programmers.

PowerWindows can be run from either the Workbench or the CLI environments.

PowerWindows starts with a blank, 640 x 200 window, on the Workbench screen.
 This is the "command window". To see just how simple it is to create a
 PowerWindows interface design, get PowerWindows running and press the
 Right-Amiga N key. This will open a new window on the Workbench screen
 called "Your new window". At this stage you could immediately generate
 source for "C" or assembler which would create the data needed to exactly
 duplicate that window. But first, let's dress it up a bit..

Start by resizing the window and positioning it any way you like. It is a
 real Intuition window so the drag bar, depth-arrangement and sizing gadgets
 all work.

Next, press Right-Amiga A and read the message in the requester that pops up
 at the top of the screen. This message explains how to use the Add a gadget
 command that we have just invoked. When you have finished reading the text,
 press the OK gadget on the requester and position your mouse somewhere over
 the center of "Your new window" and click the left button. This tells PW2.5
 where you want the TopLeft pixel of your gadget's border to be drawn. Now
 drag the mouse inside the window and PW2.5 will follow your movements and
 size the area of the gadget accordingly. After you have dragged the mouse
 around for a bit, press the HELP key on your keyboard and PW2.5 will
 redisplay the original message describing what you are doing. If you forget
 which action you are expected to take or just want to CANCEL an action once
 it has already begun, you can always press the HELP key for a reminder and a
 chance to change your mind. For now, just press the OK gadget and put your
 mouse back into "Your new window". PowerWindows is still with you, waiting
 for you to make a final decision about the size of the new gadget. Click
 inside the window to tell PW when you are done.

Now you have a real window with a real BOOLEAN gadget in it, but we still need
 a menu. So press Right-Amiga M and PW will open a requester used to specify
 several options about menus, but right now we just want to key in a name for
 our first menu, so just type in "My First Menu" into the preactivated string
 gadget labeled MENU TEXT. Next press the OK gadget and the requester will
 close. Your window now has a real menu attached to it with one menuitem
 called "dummy". If you need proof, click on the drag bar of "Your new window",
 followed by the right mouse button. Your menu is there and it looks exactly
 the way it would look in your program if you generated source code for this
 window right now. So let's do that right now.

Press Right-Amiga G and a requester will open with the names of the three
 language generators that PW2.5 has built-in listed in gadgets at the top.
 Press on the language you want and then press on the word OUTPUT (not in the
 string gadget to the right of the word) and the InovaTools1 file requester
 will open allowing you to specify the complete filename for the output file
 you want to generate. Choose a filename like "ram:test.c", or at least some
 filename that you wont mind letting PW use.

Once you have specified a filename for our little test window's source code,
 the file requester will close and stuff the filename into the OUTPUT string
 gadget. If you already know the filename, of course you can key it directly
 in this box. Finally, press the OK gadget on the source code generation
 requester and PW2.5 will write a file with all the data you need to duplicate
 this simple interface in your own software.

Now, we want to save this design for later editing, of course, so press
 Right-Amiga S and the file requester will reappear to let you indicate a save
 filename. By default PW will save your file with the ".pw" extension added to
 the name, but you can use any extension you want by typing into the box on
 the file requester labeled Type and pressing RETURN, or use no extension at
 all by deleting all characters in this field and pressing RETURN. Once you
 have specified the filename press the Save gadget on the file requester and
 the save will be made. In the case of a disk error, PowerWindows will report
 it to you and allow you to try the save again.

Now that the file is saved, you can Quit PW2.5 and come back to that same file
 anytime using the Right-Amiga L option, and then just pick right up where you
 left it last time.

That was a simple PowerWindows 2.5 editing session. Now use the menu button
 to see the main menustrip, which consists of seven primary menus:

     Project
     Screens
     Windows
     Menus
     Gadgets
     Knobs
     Preferences

Each of the menus listed above are discussed in the sections following. This
 manual is organized in the same way that the menus are organized.

PROJECT:

Under the Project menu you will find the following:

     Generate source code
     Save configuration
     Save screen and/or windows
     Load screen and/or windows

     Kill everything

     Quit...

Generate source code is the whole point of PowerWindows. This command lets you
 specify the language of your choice and several other options. (For languages other than "C" and 68000
 assembler, you must use the specific language translator program provided for
 that language, which you will find on your distribution disk. These
 translator programs use the intermediate file format generated by the Save
 screen and/or windows command.) Before starting the code generation, you must
 specify the OUTPUT filename. If you don't know the filename to use, you can
 click on the word OUTPUT for a file requester. You may also specify a HEADER
 filename. The HEADER file is a file that you wish copied into the start of
 the source generated by PW. This file may contain definitions, include
 statements, or anything else. You may click on the word HEADER for a file
 requester if you need one.

You can also control which "sections" of the source code to generate. For
 example, assume you have created a source file with PowerWindows, and then
 edited it for some particular purpose; if you need to edit that design in
 the future and regenerate the source code, PW will allow you to generate
 source for only those parts of the design that have changed. Just turn off
 the sections that you do not want generated. The sections include: SCREEN,
 PALETTE, WINDOWS, GADGETS, MENUS, WINDOWTEXT, RENDER (BORDER ONLY and IMAGE
 ONLY gadgets), and EVENTS (the event handler).

The LOCAL STRUCTURES option instructs PW to make all structures generated
 local, if the target language supports such a concept. An example is static
 structures in C. Finally, the BORDERS/IMAGES GADGET option tells PW to
 generate a special gadget as a link for the render of any BORDER ONLY or
 IMAGE ONLY gadgets (see Define gadget type for details) that may exist in
 your design. In other words, rather than create the standalone linked list
 of Borders/Images that would normally be created, PW will link those lists
 into a gadget designed just for rendering that data. The gadgets have a size
 of zero, use no highlighting and are placed in the extreme TopLeft corner
 of the window that they inhabit.

Save configuration lets you save your current Preferences settings to a file
 called "devs:pw2-configuration". This file is automatically loaded when PW
 is invoked. Note that your preferences are also saved to every PW
 intermediate file that you make, and are loaded from those files.

Save screen and/or windows will save information to a file about your screen
 and windows in a format that PowerWindows can read to recreate it. If you
 wish to retain the ability to edit your current design, you must use this
 option. We suggest that you append ".PW" to the filename to indicate what
 kind of file your are saving. (The file requester also automatically looks
 for .PW files as a default.) At any time in the future, you can select Load
 screen and/or windows from the Project menu and read this file to examine
 and edit this design. Your PW Preferences settings and source code generation
 options are also stored in this file. Note that additional PW support
 programs, such as generators for other languages, use this type of file. In
 the future, INOVATRONICS will provide tools allowing other uses for this
 format.

Load screen and/or windows  loads a file generated in the above manner and
 opens the windows and screen contained therein. Note that PW will merge the
 incoming windows with any current windows you are working with. If a custom
 screen is found in the file, and you already have a custom screen, PW will
 prompt you to ask if you wish to replace the current screen with the one
 from the file. The Preferences in use are always those from the most recently
 loaded intermediate file.

Once you have loaded a file in this way, you can manipulate all of the objects
 in your design, exactly as if you had just created them. This allows you to
 easily play with interface designs, move this object here or there, and
 experiment.

One extremely practical way to make use of this feature is to create a
 "toolbox" window of gadgets or knobs that you use on a regular basis, then
 save that window as a normal PW intermediate file. Then, whenever you need a
 gadget just like one of the ones in your toolbox, you can re-load the window
 and move or clone a gadget out of that window, and into the one you are
 currently designing. After you have what you need from your toolbox, you can
 simply remove it with the Kill window command.

Kill everything will close any custom screen and all windows with which you
 are currently working. There is no undo feature. Be warned.

Quit... means just that. Make sure you've saved an editable file if there's
 any chance you might need to change the display on which you are working.
 (Re-creating a complex window with many menus and gadgets is far easier with
 PowerWindows than without it, but it IS still work.) PowerWindows will ask
 you if you wish to abandon any changes you have made, if you have not saved
 at least an editable file to disk.

SCREENS:

You can design custom screens and palettes with the Screens functions.

Define screen type will present you with a window with which you can determine
 your screen's dimensions, the number of bitplanes it uses, the pen numbers,
 default font and title for the screen. Use these gadgets to control the type
 of screen you get, select the CUSTOMSCREEN gadget, and press OK. A new screen
 will appear with the indicated characteristics. All windows that you later
 open will appear on this screen, or, if you already have windows open, they
 will be moved to this screen. Four gadgets are provided for selecting any one
 of the four standard NTSC screen sizes, however you may key any dimensions
 you like into the Width and Height gadgets at the top of the requester. PW
 will not verify that the numbers you have chosen are legal; this is your
 responsibility. To return to a Workbench screen, select the WBENCHSCREEN
 gadget and press OK.

Several flags appear under the Screen Flags section of this requester which
 are not WYSIWYG, but will be generated in your source code. The same applies
 to the CUSTOMBITMAP POINTER string and the GADGETLIST string.

To move quickly between the PW command window, which is on the Workbench
 screen, and your custom screen, you can use the F1 and F2 keys.

Screen Palette brings up a palette editor which you can use to change the RGB
 settings for your screen's colors. The colors on the requester are oriented
 left-to-right beginning with color 0. You can use the READ PALETTE FROM IFF
 gadget to specify an IFF brush filename from which to read a palette. If you
 need a file requester to help you select the proper file, click over the
 phrase READ PALETTE FROM IFF. If you modify your palette, only to later
 change your screen definition, the palette changes may be lost. A color
 palette is maintained through screen definition changes only if the number
 of bitplanes used in the old and the new custom screens is the same.

WINDOWS:

PowerWindows 2.5 lets you work with any number of windows simultaneously.
 However, all the commands relating to windowtext and menus operate only on
 the context window. For example, if you have two windows open and you tell
 PW to Redisplay, it will redisplay the current context window. You switch
 context windows by clicking inside the window that you want to become active.
 You can switch context windows only when PW is waiting for input at the main
 menu level.

Under the Windows menu heading you'll see:

     Open new window
     Grab a window
     Redisplay
     Clean up
     Edit window characteristics
     Kill window
     Write window text
     Move window text
     Edit window text

     Delete window text

Open new window opens a new Intuition window on the Workbench screen or on
 your custom screen if you have made one. You can do anything to this window
 that you like because it is an actual window. At various times, PW will read
 information from this window's structure regarding its position and size, but
 you can play with it freely. The new window automatically becomes the context
 window for windowtext and menus. To quickly reselect the PW command window,
 you can press F1, click inside the PW command window, or if Auto select is
 on, just click inside any one of your edit windows.

Grab a window is one of the most powerful PW commands. It allows you to import
 any window running at the time as a PowerWindows construct and edit it as if
 you had generated it manually. After selecting this option, you will have a
 new menustrip with the following menus:

     Screens
     Other

On the Screens menu you will find a list of all screens open at that moment,
 and a list of all windows open on each screen will be shown as subitems to
 that screen. The windows and screens are identified by their titles. If a
 screen or window has no title, its item will appear as a blank. To grab one
 of the windows listed, just select its name. The window, with all of its
 menus and gadgets will be imported into PW for instant editing. Note that
 some things are not grabbed, such as imagery, borders, or text that were
 drawn into the window individually and are not connected to any gadget or
 menu. For each gadget grabbed that uses a border for render, a custom border
 is created. You may delete or replace this border by doing border work on
 that gadget. All menus are set to USER FORMATTING when grabbed because PW
 wants to maintain the original look and positioning of the grabbed menus. If
 you are grabbing a window from a screen of a resolution different from the
 one you are designing, PowerWindows may have to change the size or origin of
 the window to make it fit. The Other menu allows you to return to the main
 menu.

Redisplay refreshes your current window, cleaning up any display problems that
 might result from your editing. The raster of your window is blanked, then
 all gadgets, knobs and windowtext are redrawn into it.

Clean up is provided to ensure that all gadgets and knobs in your window are
 actually in the displayable area of your window. For example, if you have put
 a knob or gadget in the far right-hand side of your window and you then make
 the window more narrow by resizing it to the left, those gadgets and/or knobs
 may be no longer in your view. This can cause problems, because in order to
 manipulate a gadget or knob with PowerWindows, you must be able to select it
 with the mouse. The Clean up command will move any gadgets or knobs which are
 outside the display area back into it. Also, because of gadget WYSIWYG
 relativity, it is possible for you to create a gadget with a hitbox which has
 a negative size. PW will detect any such problems and correct them when this
 command is used.

Edit window characteristics gives you the opportunity to specify the
 following:

     Detail and block rendering pens;
     Minimum and maximum window dimensions:
     Current window dimensions;
     Current window position;
     Window title;
     Window type (window or requester)
     Window ID prefix (added to all structure names for this window
     IDCMP flags and window flags

The IDCMP flags in this window can be toggled ON or OFF to include them or
 not in the generated source code, but during editing the window has IDCMP
 flags used by PowerWindows internally. (To see what they are, try grabbing
 one!) Of the normal window flags, these are WYSIWYG: WINDOWCLOSE, WINDOWDRAG,
 WINDOWDEPTH, WINDOWSIZE, SIZEBBOTTOM, SIZEBRIGHT, BACKDROP, and BORDERLESS.
 See the Amiga ROM Kernal manuals for complete descriptions of the flags
 listed on this display.

If you want PW to make a Requester structure rather than a NewWindow structure
 at source code generation time, you can hit the gadget labeled TYPE, and it
 will toggle between WINDOW and REQUESTER.

Kill window will remove the current window. Be sure to select the window you
 want to destroy before using this option, as there is no UNDO command.

Write window text lets you write a string of text to be displayed in your
 window. After keying in the text, click OK and move your pointer to the
 location in your window where you want the upper left-hand pixel of the first
 character of the text to appear. Click here (the text appears) and drag the
 pointer to position the text more exactly. Click again when your text is
 properly positioned. (Windowtext and gadgettext are different. Windowtext is
 relative to a window and in the source code is generated as a linked list of
 IntuiText structures that you can draw into the window yourself with a single
 PrintIText call. Gadgettext is relative to a gadget. If you move the gadget,
 the text will move with it. If you delete a gadget -- BAM! -- the text is
 gone too. Gadgettext is also generated in source as a linked list of
 IntuiText structures, but they are referenced by the gadget they were
 designed with and will be automatically rendered when their parent gadgets
 are rendered.)

Edit window text displays as subitems one or more text strings that you have
 previously entered for this window. (If none have been entered, this and
 subsequent menuitems are disabled.) Just select the text string subitem that
 you would like to edit. This gives you a window from which you can choose
 text pens, drawmode and font (default, TOPAZ-SIXTY or TOPAZ-EIGHTY) as well
 as edit the text and its offsets from the TOPLeft corner of the window. All
 source code needed to duplicate your text will be generated by PowerWindows,
 including TextAttr structures for the fonts. After editing, the window will
 be redisplayed with any text changes shown.

Move window text gives you the ability to move individual strings of window
 text around in the window. The movement of the text within the window will
 be relative to the position of your pointer when you first click inside your
 window. This gives you the ability to click somewhere near your text, but not
 on it, so that you can see the entire text string as you move it.

Delete window text enables you to remove unwanted text from your window. Just
 select the text to kill and POOF! It's gone.

MENUS:

Making menus with PowerWindows 2.5 is very easy. The menus that you create
 are, at all times, real menus, attached to the window with which you are
 working. Therefore, you can see what your menu looks like at any time. Plus,
 if you are working with a custom screen, you can see the menu in the
 resolution in which it will be used. To see the menus for a particular
 window, you must select that window. If the Auto select preference is ON,
 you can only select the window by clicking on one of its system gadgets, like
 a drag bar or foreground gadget. If the window has no system gadgets, you can
 add them with the Edit window characteristics command, or you can turn off
 Auto select and just click inside the window.

Under normal conditions, all menu elements are automatically positioned by
 Power Windows. This is called AUTO FORMATTING. PW will always do its best to
 see that the menuitems and subitems are visible when the menus are rendered,
 and are attractively arranged. However, you can position the items yourself,
 if you like, by setting the USER FORMATTING flag for the menu or item and
 specifying the needed pixel values. But be careful; if you use irrational
 values, your computer will respond irrationally! If you do not set the
 USER FORMATTING flag, PW will ignore any pixel values that you set.

The Menus menu deals with menus, menuitems, and menu subitems for your current
 window. Your menus are dynamically updated every time you make a change to
 them. You can append a menu to the end of the menu tree, or you can insert a
 new menu in front of others. You can rearrange the menus, delete them, etc.
 You can also do the same things with the menuitems for each menu and with the

 subitems for each menuitem. You can attach Amiga-keys to menuitems and
 subitems, and have the items checked/unchecked or enabled/disabled by
 Intuition. You can instruct Intuition to un-check certain menuitems or
 subitems when others are selected. You can also load imagery for the
 rendering of menuitems and subitems.

The Menus menu shows you:

     Append a menu
     Insert a menu before...
     Move a menu
     Edit a menu
     Work on menuitems for...

     Delete a menu

Append a menu lets you to enter the name of a new menu, choose AUTO or USER
 FORMATTING, and set/reset the MENUENABLED flag. After you OK the settings,
 PowerWindows creates a menu with that name and attaches a "dummy" menuitem
 to it. (This dummy goes away when you add a real menuitem to the menu.) All
 menus created in this manner are appended to your menustrip (i.e., list of
 menus).

Insert a menu before... shows you the menus that exist. When you select one
 of them, you will be prompted for the name of the new menu to insert before
 the selected one.

Please note that only the first 15 characters of each menu name will be
 displayed here; the full menu name will be used in your window and in any
 generated source code. This truncation applies to menuitem names, subitem
 names, gadgettext and windowtext, as well.

Move a menu lets you move a menu toward the back of the list (the end) or
 toward the front of the list (the start). You can move a menu only one
 position at a time, so you may have to invoke Move a menu several times to
 get things just so.

Edit a menu lets you change all the settings of a selected menu.

Work on menuitems for... allows you to attach menuitems, subitems, and their
 options to the menu you select. See the next section for details.

Delete a menu removes the selected menu from the menu tree. Use this one with
 caution, as it removes everything having to do with that menu, menuitems,
 subitems and all.

MENUITEMS:

When you select a menu form Work on menuitems for..., you are given a
 completely new menustrip from which to work. It has two menus:

     MenuItems
     Other

Menuitems looks, and is, similar to the Menus menu, but "menuitem" replaces
 "menu" and "subitem" replaces "menuitem", and there is one more choice on
 the menu; Work on images for..." Basically, however, you can do to menuitems
 what you did to menus:

     Append a menuitem
     Insert a menuitem before...
     Move a menuitem
     Edit a menuitem
     Work on images for...
     Work on subitems for...

     Delete a menuitem

Under AUTO FORMATTING the width of the longest hit box in your menuitem list
 determines the width of all the menuitem hit boxes in the menuitem list for
 that menu. You can pad your menuitem names with spaces to make the box wider,
 or play with the choices you get in the editing window.

Append a menuitem, Insert a menuitem before..., and Edit a menuitem all use a
 window that allows you to specify a number of Intuition menuitem flags, text
 for the item, as well as an alternate command key for the item. You can also
 control the presentation of the IntuiText rendered in your window with this
 option. The ROOM FOR CHECK and ROOM FOR ALTKEY provide some additional
 spacing to the left and right of the item render for a checkmark and an
 alternate command key, respectively. The FUNCTION gadget lets you key in a
 function or vector name for execution when this item is selected. This
 execution is performed in conjunction with the event-handler
 (please see Using the event handler for details.)

Also contained in this window is a menu which allows you to specify the items
 which the current item should mutually-exclude. (Mutual-exclude refers to one
 item which, when selected, will un-check a list of other items on the same
 menu, or other subitems of the same menuitem.) Notice that the item upon
 which you are working is also listed here because it is perfectly legal to
 make an item exclude itself, though it rarely makes any sense. As you move,
 insert or delete items from the menu, these mutual-exclude values are
 automatically maintained by PW2.5.

Work on images for... allows you to load or delete IFF brush imagery to use
 for menuitem rendering. You can load both the render (unselected) and select
 (selected) imagery. PW automatically makes the select boxes of the items in
 the list wide enough for the images to be attractively integrated, even if
 you mix images and text on a single item list.

Work on subitems for... sets up yet another new menu, just slightly different
 from the last one:

     Append a subitem
     Subitem columns(1)
     Insert a subitem before...
     Move a subitem
     Edit a subitem
     Work on images for...

     Delete a subitem

The slight difference is Subitem columns. With this option you can display
 your subitems in up to 9 columns.

Other on the Subitem menu offers a return to the Main menu or a return to the
 Menuitem menu, while Other on the Menuitem menu only lets you return to the
 Main menu.

GADGETS:

All gadgets created by PowerWindows are rectangular, but they can be virtually
 any size from a few pixels to the entire area of the window, and with the
 Clone a gadget feature you can make very professional-looking screens filled
 with gadgetry of varying sorts and colors. PW lets you create all three
 Intuition gadget types, BOOLEAN, STRING and PROPORTIONAL and work with them
 in a what you see is what you get fashion. You can also load custom imagery
 for the the render (unselected) and the select (selected) fields of a gadget.
 Additionally, most of the flags which control the gadget's appearance are
 also WYSIWYG.

With PowerWindows version 2.5, you can also work with two special types of
 BOOLEAN gadgets: PopUpGadgets and DragGadgets. Both of these new gadget types
 are meant to be used with the InovaTools1 package available from
 INOVATRONICS, Inc. If you do not intend to use InovaTools1 with your
 software, then do not use these new gadgets types in your design. PW2.5 has
 the support routines for the InovaTools1 functions built-in to it, so you
 can design these special items, even if you cannot use them in your own
 programs.

PopUpGadgets are BOOLEAN gadgets that, when pressed, will display a menu of
 your design under the mouse and allow the user to select a menuitem or
 subitem just as if a normal intuition menu were being used. You specify that
 you want a gadget to be a PopUpGadget through the Define gadget type command.
 Then you may edit the menu attached to the gadget through the Work on
 PopUpGadget menuitems command. After making a PopUpGadget, when you click on
 the gadget your special menu will be displayed under the mouse.

DragGadgets are BOOLEAN gadgets which use an image for render and may be
 dragged around the screen. You can make the gadget stay where it is put or
 rubber-band back, move around just in the window in which they are defined
 or allow them to move anywhere on the screen! You can also control the way
 in which the render image is displayed while the gadget is being dragged,
 and the dimensions of the area in which the gadget can move. Once you have
 created a DragGadget, you can click on it and drag it anywhere in your
 window.

Both of these gadget types are fully WYSIWYG within PowerWindows. A full
 discussion of their properties and how to control them are beyond the scope
 of this documentation. You must refer to the InovaTools1 manual for further
 information.

Under the Gadgets menu you'll find:

     Add a gadget
     Move a gadget
     Clone a gadget
     Re-size a gadget
     Define gadget type
     Work on gadget borders
     Work on gadget text
     Work on gadget images
     Work on PopUpGadget menuitems

     Move gadget to start of list
     Choose gadget successor
     Move gadget to end of list

     Delete a gadget

Add a gadget waits for you to click in one of your windows to position the
 TopLeft corner of your gadget's border. Drag the mouse to size the gadget
 appropriately. Click the mouse button again and the box becomes a real
 BOOLEAN gadget, hooked into your window. Note that your ability to size the
 gadget, and then later to move it, may be impeded by the status of the Gadget
 collision checking flag which, when on, will prevent the bisection of one
 gadget by another. You may wish to disable this function for special
 applications, but be aware that the designers of Intuition strongly
 discourage the practice of overlapping or intersecting gadgets.

Move a gadget lets you change the position of a gadget by clicking inside the
 gadget and dragging it to a new location. Any associated gadget text will be
 moved also. That is, its position relative to the gadget will not change.
 When moving STRING gadgets, after selecting the gadget, press return. After
 that, the gadget may be moved normally. Press the left mouse button when it
 is properly positioned. Similarly, always move PROPORTIONAL gadgets by their
 knobs, not by clicking inside the gadget's container.

You may move a gadget from one of your windows to another by simply picking
 the gadget to move and moving your mouse until it is over the window to which
 you wish to move the gadget. Then click the mouse again and the gadget will
 be removed from the old window and deposited in the new window.

Clone a gadget lets you duplicate a gadget exactly, both in terms of hitbox
 size and in terms of gadget flags, text, and imagery or borders. Select the
 gadget to clone and a new gadget, slightly offset to the BottomRight, will
 be created. Now drag the pointer to position the duplicate gadget and click
 the left mouse button when you are finished.

You can clone gadgets from one window to another in exactly the same manner
 as they are moved from one window to another, as described above.

Re-size a gadget gives you another opportunity to get that gadget just right.
 Click and hold the select button when the pointer is on the desired gadget.
 Dragging the mouse around will re-size the gadget. Click the button again
 when the gadget is the correct size.

Define gadget type, after selecting a gadget to work on, gives you a new
 window full of various flag settings and decisions you can make concerning
 your gadget. From this screen, you can determine the gadget type, set its
 size and origin locations, and specify various data for the generation of
 your gadget's source code.

A few Define gadget type notes:

The relativity flags GRELRIGHT, GRELBOTTOM, GRELWIDTH, and GRELHEIGHT, if
 selected, ARE put into effect while in PowerWindows. Therefore, any changes
 made to the size of the window in which the relative gadgets reside, will
 effect the position and/or size of the relative gadgets. Be careful: it is
 possible, for instance, to make a gadget with the GRELWIDTH flag set, then
 resize its containing window to be so small that the gadget attains negative
 dimensions. Intuition will not object, but it will be impossible for your
 user or yourself to select this gadget. Use the Clean up command from the
 Windows menu to fix any problems arising from the use of this WYSIWYG
 feature.

BORDER-ONLY and IMAGE-ONLY gadgets are gadgets only in the context of a
 PowerWindows editing session. At the time of source code generation, all of
 the borders of the BORDER-ONLY gadgets will be written as a linked list of
 Border structures, one for each BORDER-ONLY gadget, and likewise for the
 IMAGE-ONLY gadgets. Any text associated with these gadgets is NOT GENERATED
 AT ALL. Use BORDER-ONLY gadgets to draw boxes around groups of gadgets and
 text, as we have done with this screen, and use IMAGE-ONLY gadgets to place
 various images around your display.

PopUpGadgets are BOOLEAN gadgets that have a PopUpMenu attached to them for
 use with InovaTools1.

DragGadgets are BOOLEAN gadgets that can be dragged around the display and
 use imagery for render. Selecting this option will bring up a requester
 allowing you to indicate the dimensions of the DragGadget's bounding-box, as
 well as the various flags used by DragGadgets. Also, if the language you are
 working with supports vectored execution, you can specify a routine to be
 executed each time the DragGadget is moved by the user. The string describing
 this routine is generated in your source code.

In the BOOLMASK gadget, you can specify a pointer to a BOOLMASK for use in a
 BoolInfo structure. PW will not generate a BoolInfo structure unless you put
 a string into this field.

In the EXCLUDE, GADGETID and USERDATA gadgets, you can enter any text strings
 that you want used for these same fields in the Gadget structure. Because
 these fields are not used by Intuition, you can use them for your own data.
 You must provide any data necessary to resolve these references at compile
 or run time.

The FUNCTION gadget lets you specify a function or vector which is to be
 executed when this gadget is selected. See Using the event-handler for more
 details.

In the SOURCE LABEL gadget, you can enter the exact text for the structure
 name to use when generating source for this gadget. Does not apply to
 BORDER-ONLY or IMAGE-ONLY gadgets.

The number in the string gadget LENGTH field must include one extra byte for
 the end-of-line null byte required by Intuition.

If you turn on the UNDOBUFFER gadget, PW will generate one undo buffer for
 all those gadgets that refer to it. The buffer will be as large as the
 largest string gadget buffer.

The HBODY and VBODY values are a convenient way to indicate the size of the
 AUTOKNOB of proportional gadgets and the distance which the knob can move
 each time the gadget's container is hit. A value of 10, for example, will
 make the AUTOKNOB 1/10 the size of the entire container and it will move 1/10
 of the container each time the container is hit.

Please see the Amiga ROM Kernal manuals for complete descriptions of all the
 Gadget flags listed on this screen.

Work on gadget borders concerns your control of a gadget's border. After you
 choose the gadget to work with, you have a new menu with the following
 topics:

     Borders
     Other

On the Borders menu, you will find three functions for the drawing of custom
 borders (1. freehand - where you click in your window, drag and click to set
 the end-point of that vector, and double-click when down; 2. rectangle -
 where you click for the TopLeft corner of the rectangle, drag and click when
 done; and 3. square - in which you click to set the center of the square and
 drag to define its size), a command to edit the offsets, drawmode and pen
 number of the border (for custom border or standard border), and a command
 to delete any custom border. The Other menu lets you turn off the standard
 border, pick a new gadget to work on, or return to the main menu.

If you turn off the standard border (not the same as border-only), the gadget
 border will still be displayed by PowerWindows for purposes of editing and
 identification. Any source code generated, however, will not have a gadget
 border structure referenced or generated. In order to generate a gadget with
 absolutely no render, you MUST turn off the standard border.

Work on gadget text gives you a new menu that is identical in function to the
 functions concerning windowtext in the Windows menu. Note, however, that
 windowtext is relative to a window and gadgettext to a gadget. Otherwise the
 principles are the same. Write the text, position it in the window by
 clicking and dragging the mouse, and click again when all is as it should
 be.

Work on gadget images lets you pick a gadget for which to load imagery, then
 gives you a new menustrip relating to imagery for that gadget. You can load
 an IFF brush for the gadget render of the gadget select image, edit the
 offsets for the image, make the gadget hitbox the exact same size as the
 image, or delete image. PW will automatically set the correct flags in the
 gadget structure allowing you to use the image, delete it, etc., without
 worrying about the render or highlighting flags.

Work on PopUpGadget menuitems allows you to edit the menu attached to a
 PopUpGadget just as if it were a normal PowerWindows menu. After choosing
 this option, simply click on the PopUpGadget with which you wish to work,
 and PW2.5 will give you a new menustrip for editing the menuitems attached
 to your PopUpGadget. You can do anything to a PopUpGadget's menuitems that
 you can do to a normal menu's items, including the use of imagery, subitems,
 various highlighting methods and mutual-exclusion of other items on the same
 PopUpMenu. You cannot, however, use alternate command key sequences for
 PopUpGadgets because Intuition would confuse these keys with those reserved
 for common Amiga menus.

Move gadget to start of list lets you pick a gadget to move to the start of
 the gadget list. This command and Move gadget to end of list can be used to
 crate lists of gadgets in an exact order. This lets you use only part of a
 gadget list in a given situation.

Specify gadget successor lets you indicate that "this" gadget comes right
 after "that" gadget in the list. In the event that two gadgets overlap,
 this command lets you control which gadget is in "front".

Delete a gadget deletes whatever gadget you choose. To delete a string
 gadget, you must select and press RETURN. Be careful! There is no going
 back.

KNOBS:

Knobs are special, new input devices supported by InovaTools1. They have the
 appearance of circular, analog-type dials. They can be rendered in any of the
 standard resolutions and are highly configurable. To use a knob, simply click
 in the body of the knob. If the arrow of the knob (the dial, in other words)
 is not already at the position on the knob where you clicked, it will move
 there. Then, as you move the mouse the knob arrow will move around the knob
 to a new setting. To stop moving the dial, just release the mouse select
 button.

A complete discussion of knob properties can be found in the InovaTools1
 documentation, and you must have that software in order to make knobs
 function in your software.

If you look at the Knobs menu, you will see the following options available:

     Add a knob
     Move a knob
     Clone a knob
     Re-size a knob
     Edit knob parameters

     Delete a knob

Add a knob works very much like Add a gadget. After choosing this  option,
 click at the point inside your window at which you want the center of the
 knob to appear. Then you simply drag your mouse to size the knob. When the
 outline of the knob's diameter looks correct to you, click on the mouse again
 inside the window and a real Knob will be added to your window. You can
 change its size, position and many other options with the other commands
 from this  menu.

Move a knob works in this way: click on the knob you want to move, drag it
 (even to a new window if you like) and click again when it is properly
 placed. If you move a knob to another window, the knob will be removed from
 the window of origin, and appended to the KnobList of the destination.

Clone a knob is the functional counterpart of Clone a gadget. Just click on
 the knob to clone and an exact duplicate knob will be created that you can
 then move to someplace in that same window or to another window if you so
 choose.

Re-size a knob allows you to click on the knob to resize, drag the mouse and
 then click again when the knob has reached the desired dimensions. Because
 certain rasters and memory must be allocated in order to fill a knob with a
 particular color, making a knob too large can result in a knob that cannot be
 filled.

Edit knob parameters will wait for you to select the knob you want to edit
 with the mouse, then will open a requester with gadgets inside it for all of
 the various flags and settings that can be determined for knobs. Although
 you must refer to the InovaTools1 manual for a thorough discussion of all
 these parameters, below is a short list of the items you can control with
 this command:

     X and Y coordinates of the knob's center;
     knob flags, including DRAW, FILL, COMPLEMENT, RANGED,
          CALCVALUE, MARKED, and MARKENDS;
     the current settings for the knob's position, range of
          movement, and the number of unique steps in its range;
     the radius of the knob and the length of the knob's arrow
          (dial);
     the colors used for rendering the knob;
     the label to be used in the generated source code for this
          knob;
     fields to name the text strings for the UpdateRoutine,
          KnobID, and UserData fields of the Knob structure.

When you have properly set all of the knob's parameters click on the OK gadget
 and the knob you changed will be redisplayed, reflecting your changes. Note
 that if you happen to accidentally move a knob beyond the edge of your
 window, you may use the Clean up command to bring all knobs and gadgets back
 into the boundaries of a selected window.

Delete a knob waits for you to click on the knob you want to delete and then
 removes it from the KnobList of its window. The window is then redrawn
 without the knob.

PREFERENCES:

This menu gives you some flexibility in using PowerWindows 2.5. In it, you'll
 see:

     OK prompts
     PW backdrop
     Auto Redraw
     Auto Select
     Mouse coordinates
     Gadget collision checking
     Image color remapping
     Image compression
     Trim extra bitplanes
     Source code comments
     Source code spacing (TAB)

The default condition for all of these settings is ON, except for the PW
 backdrop option. However, these settings, along with other relevant data,
 are stored in each PW intermediate file that you save, and are restored when
 the PW intermediate file is reloaded.

OK prompts, when checked, gives you a prompting requester at the start of many
 gadget and text related functions. At these prompts, you also have the
 ability of cancelling your action. You can disable these prompts by
 un-checking OK prompts in this menu. You can get the prompt back at any time
 in the middle of a function by pressing the "HELP" key. You will get the
 original help prompt back with the same chance to cancel the operation.

PW backdrop controls the PW command window. If this is checked, then it
 becomes a backdrop window. This means that no window opened can appear behind
 the PW command window. Normally, this provides a working area for your
 custom window design. However, if you wish to make the PW command window
 smaller, or design your own backdrop window, then use this option to make PW
 use a standard window.

Auto redraw lets you stop PowerWindows from redrawing your window after every
 change you make.

Auto select, when checked, tells PowerWindows that each time you click the
 left mouse button, or select a gadget, in one of your windows, that the PW
 command window should be activated. This way, the PW menus are always
 available. However, if you are doing a significant amount of menu editing,
 and are not using a drag bar in your window for safe selects, then you may
 wish to turn this function off so that you can easily select your window in
 order to inspect your menus.

Mouse coordinates, when set, shows the absolute X and Y coordinates of the
 mouse on the right side of the PW command window's title bar, during certain
 gadget and text related functions.

Gadget collision checking, when checked, makes sure that your gadget hit boxes
 do not bisect one another. If you disable this, gadgets can appear on top of
 each other, which can cause some problems for the user. Note that the
 creators of Intuition strongly discourage this practice.

Image color remapping instructs PW to modify the colors of each IFF brush
 image that you load. The purpose of the modification is to best realize the
 original intent of the colors used in the IFF image, when working with a
 palette which is different from that of the image.

Image compression makes PowerWindows detect and remove any bitplanes in an
 image which are all 0 or all 1. The image variables, PlanePick and PlaneOnOff
 are adjusted accordingly. This saves memory and reduces the amount of
 ImageData PW generates. Note, however, that if PW performs Image color
 remapping on an image, then planes that were candidates for compression may
 be used to represent the remapped colors.

Trim extra bitplanes forces each image loaded to consist of no more bitplanes
 than in the screen onto which it is loaded. If the image is not to be moved
 at runtime, from one resolution to another, this option simply throws away
 undisplayed data.

Source code comments, when checked, lets you tell PowerWindows to include a
 comment for almost every line of generated source code, explaining what
 element of each structure that source line represents. Excluding the comments
 results in a smaller, less understandable source file.

Source code spacing allows you to set the number of spaces PowerWindows will
 indent each source line with. Alternatively, you can choose TAB as a
 separator, which is the default.

OTHER TOPICS:

Repeating commands: The F10 key will repeat the last menu command that you
 gave to PW. In several instances, however, PW will not allow a command to be
 repeated because it is no longer valid or because your verification should
 be required, as in the deletion of text or menus, etc.

Cancelling commands: When using the gadget and text commands which require
 you to click in your window, you can press the "HELP" key at any time to
 redisplay the OK prompt that explains the current procedure. From that
 prompt, you can press CANCEL to abort the current command.

Using the event-handler: The event-handler that PowerWindows can generate uses
 the data that you would normally receive in an IntuiMessage from Intuition.
 You can specify function addresses for gadgets, nemuitems and subitems.
 There is a string gadget labeled FUNCTION found on the editing requesters
 for each of these objects which you must fill in with the proper text for
 your target language. PowerWindows will generate a single event-handler for
 all of these structures. You process your IntuiMessages in the following
 ways:

     Gadgets:
          wait for an IntuiMessage of GADGETUP or GADGETDOWN
          get the object address from the IntuiMessage (this is
                    the gadget_address)
          Reply the message to free Intuition for other tasks
          invoke the event-handler with
                    HandleEvent(gadget_address)
     MenuItems and Subitems:
          wait for an IntuiMessage of MENUPICK
          get the code field from the IntuiMessage (this is the
                    MENUNUM)
          Reply the message to free Intuition for other tasks
          get the item_address from Intuition with
                    itemAddress(MENUNUM);
          invoke the event-handler with
                    HandleEvent(item_address);

The event-handler will, if the gadget or menuitem is matched, execute the
 indicated function, passing the same object address through to the function
 as a parameter. Please see the example file for the language your are working
 in for specific details.

Troubleshooting:

"I can't get PW to show its menu!": Try clicking in one of your windows and
 pressing F1. This will bring PW to the front and activate its window.

"I can't get my custom menu to display!": Turn Auto Select off and click in
 your window. Press F1 when finished to return to the PW main menu. Or, select
 the drag bar, foreground or close gadget of the window and then you can look
 at your menu. Click inside it again to go back to the PW command menu or
 press F1.

"How do I make a custom knob for a PROPGADGET?": Declare a proportional
 gadget and load in the IFF brush for the knob. You can load brushes for
 both the unselected and selected knob render. Ta-da!

"When I load in an image, PowerWindows seems to HANG!": PW is just remapping
 the image. Sometimes, it can take a while. A 320 x 200, 5-bitplane image can
 take up to 16 seconds to remap. Don't panic, just wait. Or, if you don't need
 color remapping, turn off the Image color remapping flag under the
 Preferences menu.

"I'm lost and I don't know what to do!": You are probably in the middle of a
 gadget command. Press HELP. It will tell you what you are doing and let you
 cancel or continue doing it. If that doesn't work, click inside one of your
 edit windows or the PW command window and press F1. This should return you
 to the PW command level.

These docs are brought to you by River Boy.